issueURL

#3

この PR で対応する範囲 / この PR で対応しない範囲

対応する範囲

• CLIツール planloop にレビューループの基本機能（planloop run, planloop status, planloop init）を実装
• Claude Codeが作成した実装計画をCodex CLIでレビューし、レビュー指摘をClaude CLIで修正するループの半自動化
• 構造化JSON出力によるレビュー結果の機械的な管理
• 人間によるトリアージ（初回必須、以降は新規HIGH時のみ）
• Waiver（免除ルール）の永続化と自動フィルタリング
• エビデンス検証（GitHub/Figma/Context7/Web検索の利用確認）

対応しない範囲

• Claude Codeスラッシュコマンドとしての再実装（Claude Codeスラッシュコマンドとしてのレビューループ実装（/codex-review） #4 で対応予定）
• 実機テストで判明した以下のUX課題の根本解決は Claude Codeスラッシュコマンドとしてのレビューループ実装（/codex-review） #4 に委ねる:
  • Codex/Claude共にfresh runのため前回の文脈を覚えない問題
  • 毎ラウンドのトリアージが重い問題
  • 途中介入の柔軟性

変更点概要

なぜこの実装か

Zenn記事「AIコーディングの技術負債・理解負債排除手法」 のステップ2.2〜2.5で手動実施しているレビュー往復（最大10往復以上）を自動化するため。現状は都度Markdownファイルパスを変えてCodexにレビューを依頼し、結果をClaude Codeに渡す作業を手動で行っている。

アーキテクチャの選択理由

• CLI wrapper方式: SDKではなくCLI（claude -p, codex exec）をchild_processで呼び出す。認証やレート制限の問題を回避するため
• 構造化出力: OpenAI Structured Output（--output-schema）でレビュー結果をJSON形式で取得。additionalProperties: false と全プロパティの required 指定が必要（OpenAI APIの制約）
• アダプターパターン: レビュー実行と修正実行のインターフェースを分離し、将来的にClaude/Codex以外のAIエージェントに差し替え可能な設計
• 半自動オーケストレーション: 完全自動化は過剰指摘の永久ループを招くため、初回は必ず人間のトリアージを挟む設計

実機テストで得られた知見と対応

実機テスト（別プロジェクト lgtm-cat-ai-agents で検証）の過程で以下を修正済み:

• OpenAI Structured Outputの制約対応（additionalProperties: false、nullable lineRef）
• Zodバリデーションでの null → undefined 変換（z.string().nullable().optional().transform()）
• claude -p --output-format stream-json に --verbose が必要
• 子プロセスのtimeout/close/errorイベントの競合防止（settled フラグ）
• 進捗表示の追加（Codex実行中のツール呼び出し・レビュー結果をstderrに表示）
• トリアージUXの改善（viエディタ起動 → ファイルパス表示 + stdin確認方式に変更）

実機テストの結論

スタンドアロンCLI方式では以下の限界が判明し、Claude Codeスラッシュコマンドとしての再実装を #4 として起票済み:

• 3つのCLI間をファイルで中継する構成が本質的に重い
• セッション引き継ぎなしでは同じ指摘が繰り返される
• 対話的なトリアージはClaude Codeの会話UIの方が自然

レビュアーに重点的にチェックして欲しい点

• src/adapters/codex-cli.ts: OpenAI Structured Output制約への対応が正しいか（additionalProperties: false、nullable lineRef、required に全プロパティ）
• src/core/loop-runner.ts: ループの停止条件（no_blocking_findings, stagnation, max_rounds, human_abort）の正しさ
• src/core/triage.ts: HTMLコメントベースのフィードバック抽出ロジック
• tsconfig.json: types: ["node"] の追加が既存の設定と矛盾しないか

補足情報

• 追加した依存ライブラリ: commander, zod, yaml, picocolors（全て .npmrc の save-exact=true によりバージョン固定）
• テスト: 112テスト全パス（15テストファイル）
• 3回のコードレビュー・改善サイクルを実施済み（子プロセス競合防止、グローバル正規表現lastIndex修正、tmpディレクトリクリーンアップ等）